fix(test): make the reconcile-lease tests deterministic - #181

🟢 SAFE TO MERGE

Test-only change. No new decisions. All gates green on f9ab2fe, including the full Quality run (typecheck, lint, test, coverage). Codex (adversarial, in place of CodeRabbit — rate limited, no walkthrough produced): 6 findings — 4 real and fixed, 1 wrong, 1 valid but out of scope (raised below for the maintainer).

src/store/gmail-watch-state.test.ts fails on roughly half of all runs of the file alone — observed 4 of 6 on clean main, before any change. A gate that fails half the time is not a gate; it masks real regressions. This makes it deterministic.

src/store/gmail-watch-state.ts is untouched.

Root cause

The lease token is claimed_until — now() + leaseMs — and PGlite's now() advances only in whole milliseconds (verified: its ::text rendering never carries sub-millisecond digits). Two claims of the same leaseMs landing in the same millisecond therefore render the identical token:

AssertionError: expected '2026-08-02 11:48:36.747-08'
             not to be '2026-08-02 11:48:36.747-08'

Both failing assertions were expect(second).not.toBe(first) — in "claiming succeeds again once the previous lease has expired, returning a NEW token" and "a stale holder cannot clobber a live successor's lease".

The expireReconcileLease helper rewound claimed_until with UPDATE ... SET claimed_until = now() - interval '1 second'. That fakes the expiry without the elapsed time the expiry implies, so the successor's claim ran in the same millisecond as its predecessor's and the two tokens came back equal.

In production a successor can only claim once the prior lease has actually expired — i.e. at least leaseMs later — so its claimed_until is necessarily later and the tokens necessarily differ, whatever the clock's precision. The SQL shortcut was the only thing removing that guarantee.

Not a sub-millisecond boundary in the token comparison, and not a flaw in the token-as-text design (store module doc, "Why the token is text, not a Date") — that reasoning holds unchanged.

Fix

Expire the lease the way production does: advance the clock. PGlite reads the JS system clock for now() (verified), so the lease describe block pins a frozen, fixed clock and fakes Date only:

vi.useFakeTimers({ toFake: ['Date'] })   // setTimeout stays real, so nothing PGlite relies on stalls
vi.setSystemTime(FROZEN_NOW)             // constant instant — no wall-clock dependence left

and the helper jumps the clock to leaseMs + 1 ms past the claim. No retries, no widened tolerances, no sleeps. Both tests assert exactly what they asserted before.

Verification

1. Reproduced first on unmodified main — 4 of 6 runs failed.
2. 12/12 consecutive green runs of the file alone (re-run after the review fixes).
3. Not vacuous — reverting the store's AND claimed_until = $2::timestamptz release guard still fails the stale-holder test, so the safety property is still under test.
4. Full suite: 1340 passed, 0 failed. tsc: 0 errors in the changed file. Biome: clean.

Review adjudication

CodeRabbit was rate limited (Review limit reached, no walkthrough, no inline comments, no review object) so an adversarial Codex pass was run in its place, prompted against the specific invariants at risk. Its 6 findings:

Finding 3 — flagged for the maintainer, not fixed here

The reviewer is right that the lease token is a timestamp, not an identifier, so it is not a true ownership proof. Its concrete failure scenario is not reachable in this codebase today: it requires two claims colliding within one microsecond of real Postgres's now() and a retried release — and gmail-reconcile.ts:629 releases exactly once inside a finally, catching and swallowing errors without retry.

Making the token a real ownership proof would mean a dedicated random lease_token column — a schema migration and a product change, well outside a test-only de-flake. Raising it rather than acting on it.

Scope notes

• Only this file had the pattern. src/mail/ingest.test.ts and src/providers/adapters/postgres-queue/index.race.test.ts use the same SQL lease-rewind but never compare two tokens, so they are not exposed.
• Unrelated, pre-existing: 14 test files fail to load locally because imapflow and nodemailer are declared in package.json but not installed. Zero test failures result. Not touched here.

🤖 Generated with Claude Code